Scenes
Create Scene
POST https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes
Initiates the creation of a scene that requires subsequent deployment for activation.
Request Body
The scene to create.
- Curl
- Response
curl -L -X POST 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ==' \
--data '{
"description": "Hero fights a huge dragon in the magic forest.",
"characters": [
{
"character" : "workspaces/{workspace_id}/characters/{character_name}"
}
],
"displayName": "Forest Battle",
"commonKnowledge": [
"workspaces/{workspace_id}/common-knowledge/{common_knowledge_id}"
]
}'
{
"description": "Hero fights a huge dragon in the magic forest.",
"characters": [
{
"character" : "workspaces/{workspace_id}/characters/{character_name}"
}
],
"displayName": "Forest Battle",
"commonKnowledge": [
"workspaces/{workspace_id}/common-knowledge/{common_knowledge_id}"
]
}
Get Scene
GET https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scene/{scene_name}
Get a specific scene within a workspace.
Request Body
Specifies standard view or view with meta info in the response.
- Curl
- Response
curl -L -X GET 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='
{
"name": "workspaces/{workspace_id}/scenes/forest_battle",
"description": "Hero fights a huge dragon in the magic forest with axe",
"sceneTriggers": [],
"displayName": "Forest Battle",
"meta": null,
"commonKnowledge": [
"workspaces/magic_world/common-knowledge/{common_knowledge_id}"
],
"timePeriod": "",
"characters": [
{
"character": "workspaces/{workspace_id}/characters/{character_name}",
"displayTitle": "Axeon the Enchanted",
"imageUri": "",
"additionalAgentInfo": ""
}
]
}
Deploy Scene
POST https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}:deploy
Asynchronously deploys the scene. The deployment process is managed as a long-running operation (LRO). The progress and result of this operation should be monitored using the returned LRO object. Upon successful completion, all characters will reflect the updates during their interactions. In the event of a failure, the operation should be retried.
- Curl
- Response
curl -L -X POST 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}:deploy' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='
{
"name": "workspaces/{workspace_id}/scenes/{scene_name}/operations/{operation_id}",
"metadata": {
"@type": "type.googleapis.com/ai.inworld.studio.v1alpha.DeploySceneAsyncMetadata"
},
"done": false
}
List Scenes
GET https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes
Returns a list of scenes that can be filtered by several criteria. When using pagination, ensure that all other parameters provided initially remain unchanged.
Filters can be applied to ListCommonKnowledgeRequest. Filters follow the Google AIP-160 guidelines.
- Single Filter: This filter accepts only the full resource name of the scene.
For example, to filter a specific character, use
scene.name=workspaces/{workspace_id}/scenes/{uuid}
. - Multiple Filters: You can also combine multiple filters using the 'OR' condition.
For instance, to filter by two different scenes,
use
scene.name=workspaces/{workspace_id}/scenes/{uuid1} OR character.name=workspaces/{workspace_id}/scenes/{uuid2}
.
Request Body
int32
Indicates the number of items to retrieve per page. Default is 50.
string
A page token, received from a previous ListScenes
call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to ListScenesRequest
must stay the same.
string
Scenes filter. Filters follow the Google AIP-160 guidelines
- Curl
- Response
curl -L -X GET 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='
{
"scenes": [
{
"name": "workspaces/{workspace_id}/scenes/{scene_name}",
"description": "Hero fights a huge dragon in the magic forest.",
"sceneTriggers": [],
"displayName": "Forest Battle",
"meta": null,
"commonKnowledge": [
"workspaces/{workspace_id}/common-knowledge/{common_knowledge_id}"
],
"timePeriod": "",
"characters": [
{
"character": "workspaces/{workspace_id}/characters/{character_name}",
"displayTitle": "Axeon the Enchanted",
"imageUri": "",
"additionalAgentInfo": ""
}
]
},
{
"name": "workspaces/{workspace_id}/scenes/{scene_name}",
"description": "Fight with a dragon in the magic forest",
"sceneTriggers": [],
"displayName": "Forest Fight",
"meta": null,
"commonKnowledge": [],
"timePeriod": "",
"characters": [
{
"character": "workspaces/{workspace_id}/characters/{character_name}",
"displayTitle": "Axeon the Enchanted",
"imageUri": "",
"additionalAgentInfo": ""
}
]
}
],
"nextPageToken": ""
}
Update Scene
PATCH https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}
Updates the specified character. Changes to the character are not reflected in conversation until the character is deployed.
Request Body
The scene to update.
- Curl
- Response
curl -L -X PATCH 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ==' \
--data '{
"description": "The hero completes the fight within the magic forest.",
"characters": [
{
"character" : "workspaces/{workspace_id}/characters/{character_name}"
}
],
"displayName": "Forest Battle",
"commonKnowledge": [
"workspaces/{workspace_id}/common-knowledge/{common_knowledge_id}"
]
}'
{
"description": "The hero completes the fight within the magic forest.",
"characters": [
{
"character" : "workspaces/{workspace_id}/characters/{character_name}"
}
],
"displayName": "Forest Battle",
"commonKnowledge": [
"workspaces/{workspace_id}/common-knowledge/{common_knowledge_id}"
]
}
Delete Scene
DELETE https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}
Delete a specific scene within a workspace.
- Curl
- Response
curl -L -X DELETE 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='
{}
Check Deployment Status
GET https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}/operations/{operation_id}
Retrieves the current status of a long-running operation. Clients can use it to periodically poll for the operation's result, following the interval recommendations provided by the API service. This approach is useful for tracking the progress and completion status of operations that are not immediately finalized.
- Curl
- Response
curl -L -X GET 'https://api.inworld.ai/studio/v1/workspaces/{workspace_id}/scenes/{scene_name}/operations/{operation_id}' \
-H 'Grpc-Metadata-X-Authorization-Bearer-Type: studio_api' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic WlpONVlON01ETU5HSQ=='
{
"name": "workspaces/{workspace_id}/scenes/{scene_name}/operations/operation_id",
"metadata": {
"@type": "type.googleapis.com/ai.inworld.studio.v1.DeploySceneAsyncMetadata"
},
"done": true,
"response": {
"@type": "type.googleapis.com/ai.inworld.studio.v1.DeploySceneAsyncMetadata"
}
}
Schemas
Scene
string
Immutable. This field can't be set or changed via API. Automatically generated resource name by the system based on display_name property.
string
Scene's description. This field should give clear information about the scene.
List of assigned triggers and scenes.
string
User specified name.
Immutable. This field can't be set or changed via API. Meta character information.
string
List of assigned common_knowledge (contains resource references).
string
Current time period.
List of references to scene characters.
Meta
int32
Immutable. This field can't be set or changed via API. Indicates the number of triggers created in scene.
int32
Immutable. This field can't be set or changed via API. Indicates the number of characters created in scene.
int32
Immutable. This field can't be set or changed via API. Indicates the number of common knowledge created in scene.
SceneCharacterReference
string
The resource name of the referenced character. Format: workspaces/{workspace}/characters/{character}
string
Immutable. This field can't be set or changed via API. Character display title.
string
Immutable. This field can't be set or changed via API. Character display image.
SceneTrigger
string
Reference to the trigger.
string
Scene-trigger description.
SceneItemView
SceneGetView defines what dependency info should be provided in response. For now only Meta(s) part is optional
Name | Number | Description |
---|---|---|
SCENE_ITEM_VIEW_UNSPECIFIED | 0 | Not specified, equivalent to DEFAULT. |
SCENE_ITEM_VIEW_DEFAULT | 1 | Scene information by default. |
SCENE_ITEM_VIEW_WITH_META | 2 | Scene representation with meta. |