seedream

Doubao Seedance 4 0 Image Generation

Detailed model guidance is not published yet.

POST/api/v1/developer/generations

Check out Doubao Seedance 4 0 API pricing here, cheaper than Fal AI.

Model selection

Model ID	Billing	Images per request	Reference size
`doubao-seedance-4-0`	20 credits / generation	1–4 per request	Max 8 files (≤20MB)

This endpoint is asynchronous. An accepted request returns a UUID generation_id with an initial status such as queued. Use poll_after_ms to query Task Results until the task finishes.

Request headers

Header	Type	Required	Description
`Authorization`	string	required	`Bearer <token>`, using a formal account API Key (`pca_live_...`) or OAuth access token.
`Content-Type`	string	required	`application/json`
`Idempotency-Key`	string	required	UUID v4 to safely retry requests without generating duplicates.

Parameters

model_keystringrequired

Model ID to invoke: doubao-seedance-4-0.

operationstringrequired

Supported operation: image_generation.

negative_promptstringoptional

promptstringoptional

reference_upload_idsarrayoptional

parameters.aspect_ratiostringoptional

Supported aspect ratios for output generation.

1:14:33:416:99:162:33:221:95:44:5

parameters.nintegeroptional

Number of outputs to generate (1–4, default: 1).

parameters.qualitystringoptional

Image render quality.

standardhd

Output specifications

Aspect ratio	Resolutions
`1:1`	Default
`4:3`	Default
`3:4`	Default
`16:9`	Default
`9:16`	Default
`2:3`	Default
`3:2`	Default
`21:9`	Default
`5:4`	Default
`4:5`	Default

Edit a reference image

Send owned reference uploads with the same endpoint. The reference fields are ignored when the model does not support them.

{
  "model_key": "doubao-seedance-4-0",
  "operation": "image_generation",
  "prompt": "Enhance details, adjust lighting, cinematic finish",
  "reference_upload_ids": [
    "22222222-2222-4222-8222-222222222222"
  ]
}

Submit response

Returns HTTP 202 with initial task metadata upon successful acceptance. The following example illustrates the response shape; credit values come from the actual response:

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "request_id": "docs-example",
  "data": {
    "generation_id": "11111111-1111-4111-8111-111111111111",
    "status": "queued",
    "model_key": "doubao-seedance-4-0",
    "modality": "image",
    "operation": "image_generation",
    "created_at": "2026-10-14T00:00:00.000Z",
    "updated_at": "2026-10-14T00:00:00.000Z",
    "poll_after_ms": 2000,
    "estimated_credits": 10,
    "reserved_credits": 10,
    "charged_credits": 0,
    "outputs": []
  }
}

Query a task result

GET/api/v1/developer/generations/{generation_id}

Task status

Status	Meaning
queued	Queued
running	Generating
succeeded	Succeeded; read the media list from the response.
failed	Failed; read the reason from the error object. The task is refunded in full.
cancelled	Task cancelled by client request.

Billing

20 credits / generation

Credits are reserved when the task is created and settled when it completes. A failed task is refunded in full.

Common errors

Situation	Handling
`HTTP 400`	Check that every parameter value is inside the published limit and that the body matches the schema.
`HTTP 401`	Check the credential. API keys and OAuth tokens are never accepted in query strings.
`HTTP 402 / 403`	Top up the credit wallet so the estimate can be covered.
`HTTP 422`	A field failed validation. Read the field name in the error details and resend.
`HTTP 429`	Back off and retry with jitter.
Task failed / blocked	Unsupported value, missing reference, or a content-safety block. Adjust the input and retry.

doubao-seedance-4-0

curl --request POST \
  --url https://api.perchanceai.art/api/v1/developer/generations \
  --header 'Authorization: Bearer <pca_live_key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <uuid>' \
  --data '
{
  "model_key": "doubao-seedance-4-0",
  "operation": "image_generation",
  "prompt": "your prompt",
  "parameters": {
    "aspect_ratio": "1:1"
  }
}
'

import os, uuid, requests

response = requests.post(
    "https://api.perchanceai.art/api/v1/developer/generations",
    headers={
        "Authorization": f"Bearer {os.environ['PERCHANCEAI_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
    "model_key": "doubao-seedance-4-0",
    "operation": "image_generation",
    "prompt": "your prompt",
    "parameters": {
        "aspect_ratio": "1:1"
    }
},
)
print(response.json())

const response = await fetch("https://api.perchanceai.art/api/v1/developer/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PERCHANCEAI_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "model_key": "doubao-seedance-4-0",
  "operation": "image_generation",
  "prompt": "your prompt",
  "parameters": {
    "aspect_ratio": "1:1"
  }
}),
});
console.log(await response.json());

type GenerationResponse = {
  success: boolean;
  data?: { generation_id: string; status: string; model_key: string };
};

const response = await fetch("https://api.perchanceai.art/api/v1/developer/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PERCHANCEAI_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "model_key": "doubao-seedance-4-0",
  "operation": "image_generation",
  "prompt": "your prompt",
  "parameters": {
    "aspect_ratio": "1:1"
  }
} satisfies Record<string, unknown>),
});
const payload = (await response.json()) as GenerationResponse;
console.log(payload.data?.generation_id);

package main

import (
	"bytes"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
  "model_key": "doubao-seedance-4-0",
  "operation": "image_generation",
  "prompt": "your prompt",
  "parameters": {
    "aspect_ratio": "1:1"
  }
}`)
	req, _ := http.NewRequest("POST", "https://api.perchanceai.art/api/v1/developer/generations", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("PERCHANCEAI_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Idempotency-Key", "your-uuid")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	fmt.Println(res.Status)
}

<?php
$payload = json_encode({
  "model_key": "doubao-seedance-4-0",
  "operation": "image_generation",
  "prompt": "your prompt",
  "parameters": {
    "aspect_ratio": "1:1"
  }
});

$ch = curl_init("https://api.perchanceai.art/api/v1/developer/generations");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $payload,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("PERCHANCEAI_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: your-uuid",
    ],
]);
echo curl_exec($ch);
curl_close($ch);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Generate {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "model_key": "doubao-seedance-4-0",
              "operation": "image_generation",
              "prompt": "your prompt",
              "parameters": {
                "aspect_ratio": "1:1"
              }
            }
            """;
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.perchanceai.art/api/v1/developer/generations"))
            .header("Authorization", "Bearer " + System.getenv("PERCHANCEAI_API_KEY"))
            .header("Content-Type", "application/json")
            .header("Idempotency-Key", "your-uuid")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

require "net/http"
require "json"

uri = URI("https://api.perchanceai.art/api/v1/developer/generations")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer #{ENV['PERCHANCEAI_API_KEY']}"
request["Content-Type"] = "application/json"
request["Idempotency-Key"] = "your-uuid"
request.body = {
  "model_key": "doubao-seedance-4-0",
  "operation": "image_generation",
  "prompt": "your prompt",
  "parameters": {
    "aspect_ratio": "1:1"
  }
}.to_json

puts Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |http| http.request(request) }.body

using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {Environment.GetEnvironmentVariable("PERCHANCEAI_API_KEY")}");
client.DefaultRequestHeaders.Add("Idempotency-Key", "your-uuid");

var payload = {
  "model_key": "doubao-seedance-4-0",
  "operation": "image_generation",
  "prompt": "your prompt",
  "parameters": {
    "aspect_ratio": "1:1"
  }
};

var response = await client.PostAsJsonAsync("https://api.perchanceai.art/api/v1/developer/generations", payload);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_generation",
    "arguments": {
      "model_key": "doubao-seedance-4-0",
      "operation": "image_generation",
      "prompt": "your prompt",
      "parameters": {
        "aspect_ratio": "1:1"
      },
      "idempotency_key": "<uuid>"
    },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

# POST https://api.perchanceai.art/api/mcp
# Headers: Content-Type: application/json
#          X-App-Id: perchanceai
#          Authorization: Bearer <pca_live_key>
#          MCP-Protocol-Version: 2026-07-28
#          Mcp-Method: tools/call
#          Mcp-Name: create_generation

{
  "success": true,
  "code": "OK",
  "message": "OK",
  "request_id": "docs-example",
  "data": {
    "generation_id": "11111111-1111-4111-8111-111111111111",
    "status": "queued",
    "model_key": "doubao-seedance-4-0",
    "modality": "image",
    "operation": "image_generation",
    "created_at": "2026-10-14T00:00:00.000Z",
    "updated_at": "2026-10-14T00:00:00.000Z",
    "poll_after_ms": 2000,
    "estimated_credits": 10,
    "reserved_credits": 10,
    "charged_credits": 0,
    "outputs": []
  }
}

{
  "success": false,
  "request_id": "docs-example",
  "code": "BAD_REQUEST",
  "message": "Missing or malformed request payload."
}

{
  "success": false,
  "request_id": "docs-example",
  "code": "DEVELOPER_TOKEN_REQUIRED",
  "message": "A developer bearer token is required."
}

{
  "success": false,
  "request_id": "docs-example",
  "code": "CREDITS_INSUFFICIENT",
  "message": "Insufficient credits."
}

{
  "success": false,
  "request_id": "docs-example",
  "code": "DEVELOPER_SCOPE_INSUFFICIENT",
  "message": "The developer token does not include the required scope."
}

{
  "success": false,
  "request_id": "docs-example",
  "code": "MODEL_NOT_FOUND",
  "message": "Model 'doubao-seedance-4-0' was not found."
}

{
  "success": false,
  "request_id": "docs-example",
  "code": "FIELD_INVALID",
  "message": "Field value is invalid.",
  "details": {
    "field": "parameters"
  }
}

{
  "success": false,
  "request_id": "docs-example",
  "code": "RATE_LIMITED",
  "message": "Too many requests. Please throttle calls."
}

{
  "success": false,
  "request_id": "docs-example",
  "code": "INTERNAL_ERROR",
  "message": "Internal server error."
}

{
  "success": false,
  "request_id": "docs-example",
  "code": "INTERNAL_ERROR",
  "message": "Internal server error."
}