API access

Generate videos from your own tools. Same credits, same concurrency limits as the studio.

Quick start

Two calls: submit, then poll — or let the webhook tell you.

1. Submit a job

# model (optional): omit it and the default model is used.
#   Only values returned by GET /v1/video/models are accepted.
# aspectRatio (optional): 16:9 (default) | 9:16
# references: limits differ per model - see GET /v1/video/models
curl -X POST https://api.hccimagine.com/v1/video/generations \
  -H "Authorization: Bearer $HCC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "@Image_1 the character turns around, matching @Audio_1 rhythm",
    "model": "new-seedance-2.0",
    "images": ["https://your-cdn.com/character.jpg"],
    "audios": ["https://your-cdn.com/ambience.mp3"],
    "aspectRatio": "16:9",
    "webhookUrl": "https://your-app.com/hooks/hccimagine"
  }'

2. Check status

curl https://api.hccimagine.com/v1/video/generations/<id> \
  -H "Authorization: Bearer $HCC_API_KEY"

3. Download the video

# After status is "done": exchange for a download link.
# The ticket is valid 30 min, and NO web login token is needed.
# Expired? Just call /download again — the file is still there, you get a fresh link.
curl https://api.hccimagine.com/v1/video/generations/<id>/download \
  -H "Authorization: Bearer $HCC_API_KEY"
# → { "url": "https://api.hccimagine.com/api/video/result/<id>/stream?t=…", "expiresAt": "…" }

# Then download the mp4 straight from that url — it self-authenticates
# (no header needed) and supports HTTP Range for resumable downloads.
curl -L "<url from previous response>" -o video.mp4

My API keys

No keys yet.

Webhook signing secret

Verify that a callback really came from us. This is not an API key — never send it in a request.

••••••••••••••••••••••••

Authentication

Send your key as a bearer token on every request.

Authorization: Bearer sk-hcc-xxxxxxxx-…

Choosing a model

One key works across every model we open to the API. Pass model when you submit; omit it and the default model is used, so existing scripts keep working. The list changes over time — always read /v1/video/models for the current one, including each model's credits, duration, aspect ratios and reference limits.

List first, then pass — model only accepts values returned by /v1/video/models. Anything else is rejected outright — we never silently fall back to the default.
Limits follow the model — Duration, aspect ratios and reference caps differ per model. The table below shows the current default model; check /v1/video/models before you integrate.

GET /v1/video/models

curl https://api.hccimagine.com/v1/video/models   -H "Authorization: Bearer $HCC_API_KEY"

# -> { "models": [ {
#       "model": "new-seedance-2.0",    // submit with this value
#       "name": "new-seedance2.0",
#       "credits": 300,                  // credits per generation
#       "durations": [15],               // seconds
#       "resolution": "480p",
#       "aspectRatios": ["16:9", "9:16"],
#       "maxImages": 9,
#       "maxAudios": 3
#     } ] }

Reference material

You supply public https URLs. We fetch them, forward them upstream, and never store them.

Every material must be referenced — Write @Image_1, @Image_2, @Audio_1 in the prompt. A material you attach but never reference makes the job fail after several minutes with no reason given. Describing it in words is not enough.
Audio needs an image — Audio references are only accepted alongside at least one image.
URLs must be reachable — https only, and reachable from outside your own network. A download failure fails the job and refunds the credits.

	Formats	Max
Images	png / jpg / jpeg / webp	9
Audio	mp3 / wav / ogg / m4a	3

Job status

`queued`	Waiting for capacity.
`submitting` / `generating`	Being generated. Typically 3–5 minutes.
`done`	Finished. The result URL is in the response.
`failed`	Failed. Credits are refunded automatically.

Webhook

If you pass webhookUrl, we POST once when the job reaches done or failed. Timeout 10s, three retries on 5xx, no retry on 4xx.

POST https://your-app.com/hooks/hccimagine
x-hccimagine-signature: <hex>

{ "id": "…", "status": "done", "timestamp": 1786470000 }

Verify the signature against the raw request body:

const expected = crypto
  .createHmac("sha256", WEBHOOK_SECRET)
  .update(rawBody)          // 原始字节，别先 JSON.parse 再重新序列化
  .digest("hex");
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));

Retention — 24 hours

Content generated through the API is deleted after 24 hours. Download and store your results yourself; we are a pipeline, not an archive.