Skip to content

Image-to-video generation (query status)

POST /api/v5/video/status

Query the generation status and result of an image-to-video task by request ID (request_id). A successful generation returns the video URL; a failed one returns an error message.

Supported access tokens

  • AtomGit user access tokens

Anonymous access allowed

This endpoint allows anonymous access.

Request parameters

Parameter Location Type Required Description
Authorization header string No User access token; this endpoint allows anonymous access, so it may also be omitted

Request Body:

The request body is a JSON object containing the request ID issued by the image-to-video generation endpoint.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "request_id": {
      "description": "Request ID",
      "type": "string",
      "minLength": 1,
      "example": "009522a671394f3f5ac02c63b1a62662"
    }
  },
  "required": ["request_id"]
}

Response parameters

Field Type Always returned Nullable Description
request_id string Yes No Request ID (valid for 24h; retrieve the result as soon as possible)
status string Yes No Processing status; enum: running / failed / succeeded
video_url string No Yes Video URL (returned only on success, and valid for 10 minutes)
error_message string No Yes Error message (present only on failure)

Error response

The endpoint returns 400 when parameter validation fails, the user is not logged in, or the business operation fails (status failed), and 500 on a system error.

400 Invalid parameters or business failure

{
  "request_id": "009522a671394f3f5ac02c63b1a62662",
  "status": "failed",
  "error_message": "User is not logged in"
}

500 System error

{
  "request_id": "009522a671394f3f5ac02c63b1a62662",
  "status": "failed",
  "error_message": "System error; please retry later"
}

HTTP status codes

Status code Description
200 Success (OK) — the query succeeded with status succeeded or running
400 Invalid parameters or business failure (Bad Request)
500 Internal system error (Internal Server Error)

Request example

Parameter notes

Replace <request_id> with the request ID returned by the image-to-video generation endpoint, and <token> with your AtomGit user access token. This endpoint allows anonymous access, so the authentication header may be omitted.

cURL

curl -X POST 'https://api.atomgit.com/api/v5/video/status' \
  -H 'Authorization: <token>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"request_id": "<request_id>"}'

JavaScript

// Native fetch (Node.js 18+ / browsers)
const response = await fetch("https://api.atomgit.com/api/v5/video/status", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Authorization": "<YOUR-TOKEN>",
  },
  body: JSON.stringify({
    request_id: "<request_id>",
  }),
});

if (!response.ok) {
  throw new Error(`Request failed: ${response.status}`);
}

const data = await response.json();
console.log(data);

Python

import requests

resp = requests.post(
    "https://api.atomgit.com/api/v5/video/status",
    headers={
        "Content-Type": "application/json",
        "Accept": "application/json",
        "Authorization": "<YOUR-TOKEN>",
    },
    json={"request_id": "<request_id>"},
    timeout=10,
)
resp.raise_for_status()

print(resp.json())

Response example

Status code: 200

{
  "request_id": "2600c2714f184f9087060b014fb2f7a3",
  "status": "succeeded",
  "video_url": "https://ai-inference-cdn-static.gitcode.com/video-2600c2714f184f9087060b014fb2f7a3-output.mp4?auth_key=1765510460-86c58596bd5944b1af78aa3587cfb902-0-44a97eda8e44774e561eaced4dd124865c7855ca2e251f3099b3ec3aea77c62b"
}

Error codes

Error code Description
400 Invalid parameters, not logged in, or business failure (status failed)
401 Unauthenticated or invalid credentials (missing or invalid access credentials)
404 Request path does not exist
405 Request method not supported
429 Too many requests; rate limit triggered
500 Internal system error

Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc