이 페이지에서는 Video Stitcher API를 사용하여 문제를 해결하는 방법을 보여줍니다. 이 페이지에 표시된 오류는 Video Stitcher API와 관련이 있습니다. Google API의 일반적인 오류는 Cloud API 오류 페이지를 참조하세요.
첫 번째 오류만 반환됩니다. 요청에 오류가 여러 개 발생하면 반환된 오류를 수정하고 요청을 다시 만들어 다음 오류를 확인해야 합니다.
세션을 만들 때 재생 목록을 가져올 수 없음
Video Stitcher API가 지정된 sourceUri에서 동영상 매니페스트를 가져올 수 없으면 다음 문제가 발생합니다.
{
"error": {
"code": 404,
"message": "got status code 403 when fetching playlist from URI \"https://example.com/manifest.m3u8\"",
"status": "NOT_FOUND",
}
}
이 문제를 해결하려면 다음 단계를 따르세요.
제공된 sourceUri가 유효한 동영상으로 연결되는지 확인합니다.
sourceUri에 curl을 사용합니다. 매니페스트가 공개적으로 액세스 가능한 경우 URL에 공개적으로 연결할 수 있는지 확인합니다.
sourceUri가 올바르고 동영상 매니페스트에 URL 서명이 필요한 경우 다음 단계로 진행합니다.
CDN 키가 요청과 동일한 리전에서 Video Stitcher API에 등록되었는지 확인합니다.
sourceUri 호스트 이름과 일치하는 CDN 키 구성이 존재하는지 확인합니다. 구성이 존재하지 않으면 Video Stitcher API에 CDN 키를 등록합니다. 구성이 서비스에 전파되도록 5분 이상 기다립니다.
구성이 존재하면 다음 단계로 진행합니다.
URL 서명에 사용된 비공개 키가 잘못된 것으로 의심되는 경우 올바른 비공개 키로 등록된 CDN 키를 업데이트할 수 있습니다.
CDN 키가 오래됨
최근에 CDN 키를 등록하거나 업데이트했고 Video Stitcher API가 새 구성을 사용하여 URL 서명을 시작하지 않은 경우 아래 단계에 따라 문제를 진단합니다.
CDN 키가 최근에 Video Stitcher API에 등록된 경우 업데이트가 적용되도록 5분 이상 기다립니다. 문제가 지속되면 다음 단계를 진행합니다.
리전에서 하나의 호스트 이름에 하나의 CDN 키만 등록되었는지 확인합니다.
동일한 호스트 이름으로 CDN 키가 여러 개 등록된 경우 Video Stitcher API가 URL에 서명할 CDN 키 중 하나를 선택합니다.
curl-H"User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"\AD_TAG_URI
채워진 VAST 응답이 반환되면 라이브 세션을 만들 때 User-Agent 헤더를 Video Stitcher API에 전달해야 한다는 것이 문제입니다. Video Stitcher API는 광고 검색을 위해 광고 태그를 실행할 때 이 헤더를 사용합니다.
여전히 비어 있는 응답이 반환되면 지정된 광고 태그에 문제가 있습니다. 고객에게 광고 태그가 올바른지 그리고 광고 태그 매크로 값도 올바른지 확인합니다.
고객의 광고 태그 문제가 해결되었지만 광고가 삽입되지 않았으면 다음 단계로 진행합니다.
라이브 세션을 검사합니다.
영향을 받는 세션에 광고가 광고 서버로부터 반환되는 것으로 표시되면 다음 단계로 진행합니다.
광고 누락을 일으킬 수 있는 다음 원인은 광고 재인코딩입니다. 이 API는 소스 동영상과 일치하도록 광고를 인코딩하기 위해 첫 번째 접촉 중에 광고를 다시 인코딩합니다. 일반적으로 광고는 인코딩하는 데 몇 분이 걸립니다. 몇 분 후 새 세션 만들기를 다시 시도하여 광고가 삽입되었는지 확인합니다.
삽입된 광고가 없으면 광고 인코딩 실패 때문일 수 있습니다.
광고 미디어 URL에 연결하지 못할 수 있습니다. 이 경우 고객이 광고 공급업체와 협력하여 해당 광고 미디어에 무엇이 잘못되었는지 확인해야 합니다.
VOD 세션에 삽입된 광고 없음
제공된 광고 태그가 비어 있지 않은 VAST 또는 VMAP 응답을 반환하는지 확인합니다.
제공된 광고 태그를 다음 안내에 따라 사용합니다.
광고 태그를 웹브라우저(예: Chrome) 주소 표시줄에 복사하고 비어 있지 않은 VAST, VMAP, SmartXML 응답을 반환하는지 확인합니다.
다음은 비어 있는 VAST 응답입니다.
광고 태그를 웹브라우저(예: Chrome, Firefox 등) 주소 표시줄에 배치하고 비어있지 않은 VAST, VMAP, SmartXML 응답을 반환하는지 확인합니다. 비어 있는 VAST 응답은 다음과 같습니다.
curl-H"User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"\AD_TAG_URI
채워진 VAST 또는 VMAP 응답이 반환되면 VOD 세션을 만들 때 User-Agent 헤더를 Video Stitcher API에 전달해야 하는 것이 문제입니다. Video Stitcher API는 광고 검색을 위해 광고 태그를 실행할 때 이 헤더를 사용합니다.
여전히 비어 있는 응답이 반환되면 지정된 광고 태그에 문제가 있습니다. 고객에게 광고 태그가 올바른지 그리고 광고 태그 매크로 값도 올바른지 확인합니다.
고객의 광고 태그 문제가 해결되었지만 광고가 삽입되지 않았으면 다음 단계로 진행합니다.
VOD 세션을 검사합니다.
영향을 받는 세션에 광고가 광고 서버로부터 반환되는 것으로 표시되면 다음 단계로 진행합니다.
광고 누락을 일으킬 수 있는 다음 원인은 광고 재인코딩입니다. 이 API는 소스 동영상과 일치하도록 광고를 인코딩하기 위해 첫 번째 접촉 중에 광고를 다시 인코딩합니다. 일반적으로 광고는 인코딩하는 데 몇 분이 걸립니다. 몇 분 후 새 세션 만들기를 다시 시도하여 광고가 삽입되었는지 확인합니다.
삽입된 광고가 없으면 광고 인코딩 실패 때문일 수 있습니다.
광고 미디어 URL에 연결하지 못할 수 있습니다. 이 경우 고객이 광고 공급업체와 협력하여 해당 광고 미디어에 무엇이 잘못되었는지 확인해야 합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[],[],null,["# Troubleshoot\n\nThis page shows you how to resolve issues with the Video Stitcher API. The errors\nshown on this page are specific to the Video Stitcher API. For information on\ngeneric errors across Google APIs, see the Cloud APIs\n[Errors](/apis/design/errors) page.\n\nOnly the first error is returned. If a request encounters multiple errors, you\nneed to fix the returned error and retry the request to see the next error.\n\nUnable to fetch playlist when creating a session\n------------------------------------------------\n\nThe following issue occurs when the Video Stitcher API is unable to fetch the\nvideo manifest from the specified `sourceUri`. \n\n```\n{\n \"error\": {\n \"code\": 404,\n \"message\": \"got status code 403 when fetching playlist from URI \\\"https://example.com/manifest.m3u8\\\"\",\n \"status\": \"NOT_FOUND\",\n }\n}\n```\n\nTo resolve this issue, follow the steps below:\n\n1. Verify that the provided `sourceUri` links to a valid video manifest.\n\n - Use `curl` with the `sourceUri`. If the manifest is intended to be publicly accessible, ensure that the URL can be reached publicly.\n - If the `sourceUri` is correct and the video manifest requires URL signing, proceed to the next step.\n2. Ensure that the CDN key has been registered with the Video Stitcher API in the\n same region as the request.\n\n - [Verify that the CDN key configuration](/video-stitcher/docs/how-to/managing-cdn-keys#list_cdn_keys) matching the `sourceUri` hostname exists. If the configuration doesn't exist, [register the CDN key](/video-stitcher/docs/how-to/managing-cdn-keys#register_cdn_key) with the Video Stitcher API. Wait at least 5 minutes for the configuration to propagate to the service.\n - If the configuration exists, proceed to the next step.\n3. If you suspect the private key used for signing the URL is incorrect, you\n may want to\n [update the registered CDN key](/video-stitcher/docs/how-to/managing-cdn-keys#update_cdn_key)\n with the correct private key.\n\nCDN key is outdated\n-------------------\n\nIf you recently registered or updated a CDN key and the Video Stitcher API has not\nstarted signing URLs using the new configuration, then follow the steps below to\ndiagnose the issue:\n\n1. If the CDN key was recently registered with the Video Stitcher API, then wait\n at least 5 minutes to allow the update to propagate. If the issue persist,\n proceed to the next step.\n\n2. Verify that only one CDN key is registered for one hostname for the region.\n If multiple CDN keys have been registered with the same hostname, the\n Video Stitcher API will select one of the CDN keys to sign the URL with.\n\n - Ensure that only one CDN key has been registered with a specified hostname for a given region. [Delete the obsolete CDN key](/video-stitcher/docs/how-to/managing-cdn-keys#delete_cdn_key).\n\nNo ads inserted in a live session\n---------------------------------\n\nIf no ads were inserted in a live session, use the following steps to diagnose\nthe issue:\n\n1. Verify that the source livestreams inserted ad breaks in the manifest. The\n following [ad markers](/video-stitcher/docs/concepts/ad-markers) need to\n exist in the livestream video manifest to indicate to the Video Stitcher API\n to replace source video segments with ad segments.\n\n - If the source video manifest does not have any ad markers, either your\n encoder hasn't triggered an ad break or needs to be changed to insert\n the supported [ad markers](/video-stitcher/docs/concepts/ad-markers).\n\n - If ad markers are clearly visible in the source manifest, then proceed\n to the next step.\n\n2. Verify that the provided ad tag returns a non-empty VAST response.\n\n - Copy the ad tag into a web browser (for example, Chrome) address bar and\n verifies that it returns a non-empty VAST response. The following is an\n empty VAST response:\n\n \u003cVAST version=\"3.0\"/\u003e\n\n - If an empty VAST response is returned, then the issue is the ad tag.\n Verify that the ad tag is set up correctly with the ad servers.\n\n - If the VAST response is populated, use `curl` to request the ad tag.\n Some ad servers require the `User-Agent`\n [header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent)\n to be provided. Try the following `curl` command:\n\n curl \u003cvar translate=\"no\"\u003eAD_TAG_URI\u003c/var\u003e\n\n - If the `curl` command returns an empty VAST response, add the\n `User-Agent` header to the `curl` command:\n\n curl -H \"User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36\" \\\n \u003cvar translate=\"no\"\u003eAD_TAG_URI\u003c/var\u003e\n\n - If a populated VAST response is returned, then the issue is that the\n `User-Agent` header needs to be passed to the Video Stitcher API when\n creating the live session. The Video Stitcher API uses that header when\n executing the ad tag to retrieve ads.\n\n - If an empty response is still returned, then the issue is with the given\n ad tag. Confirm with the customer that the ad tag is correct and that\n any\n [ad tag macro](/video-stitcher/docs/how-to/managing-live-sessions#ad-tag-macros)\n values are correct as well.\n\n - If the customer's ad tag issues have been resolved, but ads have not\n been inserted, proceed to the next step.\n\n3. [Inspect the live session](/video-stitcher/docs/how-to/managing-live-sessions#inspect-live-sessions).\n If the affected session is showing that ads are returned from the ad\n servers, then proceed to the next step.\n\n4. The next potential cause for missing ads is due to\n [ad re-encoding](/video-stitcher/docs/concepts/overview#ad_re-encoding). The\n API will re-encode ads during its first encounter to encode the ad to match\n the source video. Usually, ads take a few minutes to encode. Retry creating\n a new session after a few minutes to see if ads are inserted.\n\n If no ads were inserted, the issue may be due to an ad failing to encode.\n The ad media URLs may not be reachable. In this case, the customer needs to\n work with the ad provider to determine what's wrong with their ad media.\n\nNo ads inserted in a VOD session\n--------------------------------\n\n1. Verify that the provided ad tag returns a non-empty VAST or VMAP response.\n Use the provided ad tag with the following directions:\n\n - Copy the ad tag into a web browser (for example, Chrome) address bar and verifies that it returns a non-empty VAST, VMAP, or SmartXML response. The following is an empty VAST response:\n - Put the ad tag into a web browser (ie. Chrome, Firefox, etc) address bar\n and verifies that it returns a non empty VAST, VMAP, or SmartXML\n response. An empty VAST response looks like:\n\n \u003cVAST version=\"3.0\"/\u003e\n\n The following is an empty VMAP response: \n\n \u003cVMAP xmlns:vmap=\"http://www.iab.net/vmap-1.0\" version=\"1.0\"/\u003e\n\n - If an empty VAST response is returned, then the issue is the ad tag.\n Verify that the ad tag is set up correctly with the ad servers.\n\n - If the VAST response is populated, use `curl` to request the ad tag.\n Some ad servers require the `User-Agent`\n [header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent)\n to be provided. Try the following `curl` command:\n\n curl \u003cvar translate=\"no\"\u003eAD_TAG_URI\u003c/var\u003e\n\n - If the `curl` command returns an empty VAST response, add the\n `User-Agent` header to the `curl` command:\n\n curl -H \"User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36\" \\\n \u003cvar translate=\"no\"\u003eAD_TAG_URI\u003c/var\u003e\n\n - If a populated VAST or VMAP response is returned, then the issue is that\n the `User-Agent` header needs to be passed to the Video Stitcher API\n when creating the VOD session. The Video Stitcher API uses that header\n when executing the ad tag to retrieve ads.\n\n - If an empty response is still returned, then the issue is with the given\n ad tag. Confirm with the customer that the ad tag is correct and that\n any\n [ad tag macro](/video-stitcher/docs/how-to/managing-vod-sessions#ad-tag-macros)\n values are correct as well.\n\n - If the customer's ad tag issues have been resolved, but ads have not\n been inserted, proceed to the next step.\n\n2. [Inspect the VOD session](/video-stitcher/docs/how-to/managing-vod-sessions#inspect-vod-sessions).\n If the affected session is showing that ads are returned from the ad\n servers, then proceed to the next step.\n\n3. The next potential cause for missing ads is due to\n [ad re-encoding](/video-stitcher/docs/concepts/overview#ad_re-encoding). The\n API will re-encode ads during its first encounter to encode the ad to match\n the source video. Usually, ads take a few minutes to encode. Retry creating\n a new session after a few minutes to see if ads are inserted.\n\n If no ads were inserted, the issue may be due to an ad failing to encode.\n The ad media URLs may not be reachable. In this case, the customer needs to\n work with the ad provider to determine what's wrong with their ad media."]]
