API Reference - SeedHorse.AI

Generate high-quality AI images and videos with a single HTTP request. This API uses the same generation engine as SeedHorse Studio and is available for developers to call programmatically.

Capability Overview

Image Generation (Imagen Nano Banana Pro/2)

Text-to-Image — Generate images by inputting text prompts
Image-Text-to-Image — Generate images with reference images + text prompts

Video Generation (Seedance 2.0)

Image-Text-to-Video — Generate videos with reference images + text prompts
Image-Video-Text-to-Video — Generate videos with reference images + reference videos + text prompts
Image-Audio-Text-to-Video — Generate videos with reference images + reference audio + text prompts
Full-Modality-to-Video — Generate videos with reference images + reference videos + reference audio + text prompts

Available Models

Model	Type	Supported Generation Methods (type)
Imagen Nano Banana 2	Image	`txt`, `img_txt`
Seedance 2.0	Video	`img_txt`, `img_vid_txt`, `img_aud_txt`, `img_vid_aud_txt`

Base URL

All requests are sent to:

https://api.seedhorse.ai

The API path prefix is /api/v1.

Authentication

Each request must carry a Bearer Token in the Authorization request header:

Authorization: Bearer sh-xxxxxxxxxxxxxxxxxx

API Documentation

Submit Generation Task

POST /api/v1/task/generate

Submit a generation task and return a task ID immediately; the generation process runs asynchronously.

Request Headers

Header	Required	Description
`Authorization`	Yes	`Bearer sh-xxxxx`
`Content-Type`	Yes	`application/json`
`X-Idempotency-Key`	No	Idempotency key to prevent duplicate submissions

Request Body Parameters

Field	Type	Required	Description
`model`	string	Yes	Model name (`Seedance 2.0` or `Imagen Nano Banana 2`)
`taskName`	string	Yes	Task name
`type`	string	Yes	Generation method (see Available Models)
`prompt`	string	Yes	Text prompt describing the content to be generated
`resolution`	string	No	Video resolution: `720p` (video only)
`durationSeconds`	integer	No	Video duration (seconds), 4–15 (video only)
`aspectRatio`	string	No	Aspect ratio: `16:9`, `9:16` (image only)
`imageCount`	integer	No	Number of images to generate, max 4 (image only)
`size`	string	No	Image size: `1K`, `2K`, `4K` (image only)
`quality`	integer	No	Generation quality, 50–100
`seed`	long	No	Random seed; `-1` means random
`generateAudio`	boolean	No	Whether to auto-generate audio (video only, default `true`)
`refImageUrls`	string[]	No	List of reference image URLs (max 5)
`refVideoUrls`	string[]	No	List of reference video URLs (max 5, video only)
`refAudioUrls`	string[]	No	List of reference audio URLs (max 5, video only)

Successful Response

{
    "code": 0,
    "data": {
        "estimatedCredits": 5,
        "taskId": 9034,
        "taskNo": "3b248921b9be429b8303838118f3cd7f"
    },
    "msg": "success",
    "ok": true
}

Field	Type	Description
`data.taskId`	long	Task ID for polling progress
`data.taskNo`	string	Business task number, globally unique
`data.estimatedCredits`	long	Pre-deducted credits for this task

Query Task Status

GET /api/v1/query/{taskId}

Query the current status and generation results of a specified task.

Request Headers

Header	Required	Description
`Authorization`	Yes	`Bearer sh-xxxxx`

Successful Response

{
    "code": 0,
    "data": {
        "aspectRatio": "",
        "createTime": "2026-04-22T11:01:32",
        "durationSeconds": 0,
        "failReason": "",
        "genMethod": "img_txt",
        "generateAudio": true,
        "imageCount": 1,
        "modelId": 4,
        "negativePrompt": null,
        "progress": 100,
        "prompt": "A grey kitten",
        "quality": 80,
        "refAudioUrls": [],
        "refImageUrls": [],
        "refVideoUrls": [],
        "resolution": "720p",
        "results": [
            {
                "durationSeconds": 5,
                "failReason": "",
                "fileUrl": "https://tk-hub.oss-ap-northeast-1.aliyuncs.com/tasks/files/.../task_xxx.mp4?...",
                "height": 0,
                "subStatus": 0,
                "thumbnailUrl": null,
                "width": 0
            }
        ],
        "seed": -1,
        "size": "",
        "subTaskDone": 0,
        "subTaskTotal": 0,
        "taskId": 9055,
        "taskName": "Image-Text Video Generation",
        "taskStatus": 2,
        "taskType": 1
    },
    "msg": "success",
    "ok": true
}

Response Field Description

Field	Type	Description
`data.taskId`	long	Task ID
`data.taskName`	string	Task name
`data.taskStatus`	int	Task status (0=Queuing 1=Generating 2=Completed 3=Failed 4=Under safety review 5=Cancelled)
`data.taskType`	int	Task type (1=Video 2=Image)
`data.progress`	int	Progress percentage (0–100)
`data.modelId`	long	ID of the used model
`data.genMethod`	string	Generation method (e.g. `img_txt`, `txt`)
`data.prompt`	string	Positive prompt
`data.negativePrompt`	string	Negative prompt (nullable)
`data.resolution`	string	Resolution (video task)
`data.durationSeconds`	int	Video duration (seconds)
`data.aspectRatio`	string	Aspect ratio
`data.imageCount`	int	Number of generated images
`data.size`	string	Image size
`data.quality`	int	Generation quality (50–100)
`data.seed`	long	Random seed (-1=Not specified)
`data.generateAudio`	boolean	Whether to auto-generate audio
`data.refImageUrls`	string[]	List of reference image URLs
`data.refVideoUrls`	string[]	List of reference video URLs
`data.refAudioUrls`	string[]	List of reference audio URLs
`data.failReason`	string	Failure reason (populated on failure)
`data.subTaskTotal`	int	Total subtasks (valid for multi-image tasks)
`data.subTaskDone`	int	Completed subtasks
`data.createTime`	string	Creation time
`data.results`	array	Generation result list (populated when completed)
`data.results[].fileUrl`	string	Result file URL
`data.results[].thumbnailUrl`	string	Thumbnail URL
`data.results[].durationSeconds`	int	Video duration (seconds)
`data.results[].width`	int	Width (pixels)
`data.results[].height`	int	Height (pixels)
`data.results[].subStatus`	int	Subtask status (0=Pending 1=Success 2=Failed)
`data.results[].failReason`	string	Subtask failure reason

It is recommended to poll every 5–10 seconds until taskStatus becomes 2 (Completed) or 3 (Failed).

Quick Start

1. Submit Task

curl -X POST https://api.seedhorse.ai/api/v1/task/generate \
  -H "Authorization: Bearer sh-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Seedance 2.0",
    "taskName": "My First Video",
    "type": "img_txt",
    "prompt": "A cinematic tracking shot through a neon-lit rainy street at night",
    "durationSeconds": 5,
    "resolution": "720p",
    "aspectRatio": "16:9",
    "generateAudio": true
  }'

2. Poll Status

curl https://api.seedhorse.ai/api/v1/query/9034 \
  -H "Authorization: Bearer sh-xxxxx"

3. Get Results

When taskStatus is 2, the results array contains the URLs of the generated files. Please download and save them to your own storage as soon as possible.

Request Examples

Image Generation

Text-to-Image (txt)

{
    "model": "Imagen Nano Banana 2",
    "taskName": "Image Generation Test",
    "type": "txt",
    "prompt": "a cute orange cat sitting on a windowsill, warm sunlight, studio ghibli style",
    "aspectRatio": "9:16",
    "imageCount": 1,
    "size": "4k"
}

Image-Text-to-Image (img_txt)

{
    "model": "Imagen Nano Banana 2",
    "taskName": "Image-Text Generation Test",
    "type": "img_txt",
    "prompt": "Generate a blue kitten",
    "aspectRatio": "9:16",
    "refImageUrls": ["https://example.com/reference.jpg"],
    "imageCount": 1,
    "size": "4k"
}

Video Generation

Image-Text-to-Video (img_txt)

{
    "model": "Seedance 2.0",
    "taskName": "Image-Text Video Generation",
    "type": "img_txt",
    "prompt": "A grey kitten playing in the garden",
    "durationSeconds": 5,
    "resolution": "720p",
    "aspectRatio": "16:9",
    "generateAudio": true,
    "refImageUrls": ["https://example.com/cat.jpg"]
}

Image-Video-Text-to-Video (img_vid_txt)

{
    "model": "Seedance 2.0",
    "taskName": "Image-Video-Text Video Generation",
    "type": "img_vid_txt",
    "prompt": "A grey kitten",
    "durationSeconds": 5,
    "resolution": "720p",
    "aspectRatio": "16:9",
    "generateAudio": true,
    "refImageUrls": ["https://example.com/cat.jpg"],
    "refVideoUrls": ["https://example.com/reference.mp4"]
}

Image-Audio-Text-to-Video (img_aud_txt)

{
    "model": "Seedance 2.0",
    "taskName": "Image-Audio-Text Video Generation",
    "type": "img_aud_txt",
    "prompt": "A grey kitten",
    "durationSeconds": 5,
    "resolution": "720p",
    "aspectRatio": "16:9",
    "generateAudio": true,
    "refImageUrls": ["https://example.com/cat.jpg"],
    "refAudioUrls": ["https://example.com/music.mp3"]
}

Full-Modality-to-Video (img_vid_aud_txt)

{
    "model": "Seedance 2.0",
    "taskName": "Full-Modality Video Generation",
    "type": "img_vid_aud_txt",
    "prompt": "A grey kitten",
    "durationSeconds": 5,
    "resolution": "720p",
    "aspectRatio": "16:9",
    "generateAudio": true,
    "refImageUrls": ["https://example.com/cat.jpg"],
    "refVideoUrls": ["https://example.com/reference.mp4"],
    "refAudioUrls": ["https://example.com/music.mp3"]
}

Error Codes

Unified response format:

{
    "code": 40003,
    "msg": "Seedance 2.0 model does not exist",
    "ok": false,
    "data": null
}

System Errors (1xxxx)

Error Code	Description
10001	System busy
10006	Failed to acquire lock

Authentication/Authorization (2xxxx)

Error Code	Description
20001	Not logged in or login expired
20002	No access permission
20003	No permission to operate this task
20008	Invalid API Key

Parameter Validation (3xxxx)

Error Code	Description
30001	Invalid parameters (missing required fields or wrong parameter format)

Resource Not Found (4xxxx)

Error Code	Description
40002	Task does not exist
40003	Model does not exist or has been offline

Business Rules (5xxxx)

Error Code	Description
50001	Model disabled
50002	Channel unavailable
50003	Generation method not supported
50006	Resolution not supported
50007	Duration not supported
50008	Image size not supported
50009	Aspect ratio not supported
50010	Invalid image count
50011	Reference image required
50014	Reference content failed safety review
50015	Reference content blocked

Credit Billing (6xxxx)

Error Code	Description
60001	Insufficient credits
60002	Billing lock busy, please retry

Getting Started

​Capability Overview

​Available Models

​Base URL

​Authentication

​API Documentation

​Submit Generation Task

​Request Headers

​Request Body Parameters

​Successful Response

​Query Task Status

​Request Headers

​Successful Response

​Response Field Description

​Quick Start

​1. Submit Task

​2. Poll Status

​3. Get Results

​Request Examples

​Image Generation

​Text-to-Image (txt)

​Image-Text-to-Image (img_txt)

​Video Generation

​Image-Text-to-Video (img_txt)

​Image-Video-Text-to-Video (img_vid_txt)

​Image-Audio-Text-to-Video (img_aud_txt)

​Full-Modality-to-Video (img_vid_aud_txt)

​Error Codes

​System Errors (1xxxx)

​Authentication/Authorization (2xxxx)

​Parameter Validation (3xxxx)

​Resource Not Found (4xxxx)

​Business Rules (5xxxx)

​Credit Billing (6xxxx)

Capability Overview

Available Models

Base URL

Authentication

API Documentation

Submit Generation Task

Request Headers

Request Body Parameters

Successful Response

Query Task Status

Request Headers

Successful Response

Response Field Description

Quick Start

1. Submit Task

2. Poll Status

3. Get Results

Request Examples

Image Generation

Text-to-Image (txt)

Image-Text-to-Image (img_txt)

Video Generation

Image-Text-to-Video (img_txt)

Image-Video-Text-to-Video (img_vid_txt)

Image-Audio-Text-to-Video (img_aud_txt)

Full-Modality-to-Video (img_vid_aud_txt)

Error Codes

System Errors (1xxxx)

Authentication/Authorization (2xxxx)

Parameter Validation (3xxxx)

Resource Not Found (4xxxx)

Business Rules (5xxxx)

Credit Billing (6xxxx)